# 글벗 Light v2.0 — 전체 프로젝트 구조

> 작성일: 2025-02-06
> 기준: app.py + 전체 소스코드 분석 완료

---

## 1. 프로젝트 개요

**글벗**은 HWPX(한글) 문서를 HTML로 변환하고, AI가 내용을 채워 전문 문서를 생성하는 시스템.

### 핵심 원칙
- **HWPX 1:1 재현**: 원본 양식을 그대로 HTML로 변환
- **하드코딩 제로**: 모든 스타일은 HWPX에서 추출
- **템플릿 기반**: 양식은 유지, 내용만 AI가 채움

---

## 2. 전체 아키텍처 (16개 기능)

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              【 글벗 Light v2.0 】                            │
├──────────────────┬─────────────────────────────┬────────────────────────────┤
│                  │                             │                            │
│    【 INPUT 】    │        【 PROCESS 】        │        【 OUTPUT 】         │
│    원본 데이터    │          핵심 엔진           │          결과물            │
│                  │                             │                            │
│ ① 로컬 문서 RAG화 │    ┌─────────────────┐     │  ⑤ 기획서 생성 ✅          │
│    ✅ 구현완료    │    │                 │     │     1p / 1p+첨부           │
│    hwp,pdf,ppt   │    │  HWPX ↔ HTML   │     │                            │
│    → 텍스트 추출  │    │   변환 엔진     │     │  ⑥ 보고서 생성 ✅          │
│                  │    │                 │     │     표지/목차/본문          │
│ ② 웹 문서 수집   │    │   ✅ 구현완료    │     │                            │
│    ❌ 미구현     │    │                 │     │  ⑦ 발표자료 생성 ⏳        │
│                  │    └────────┬────────┘     │     (준비중)               │
│ ③ HTML 표준화   │             │              │                            │
│    ❓ 미확인     │             ▼              │  ⑧ 신규 문서유형 ✅         │
│                  │    ┌─────────────────┐     │     HWPX 업로드 → 등록     │
│ ④ 반영 수준 선택 │    │                 │     │                            │
│    ❓ 미확인     │    │   【 EDIT 】    │     │                            │
│                  │    │    편집 엔진    │     │                            │
│                  │    │                 │     │                            │
│                  │    │ ⑨ 웹 편집기 ✅  │     │                            │
│                  │    │ ⑩ AI 편집 ✅   │     │                            │
│                  │    │ ⑪ 신규템플릿 ✅ │     │                            │
│                  │    │                 │     │                            │
│                  │    └─────────────────┘     │                            │
└──────────────────┴─────────────────────────────┴────────────────────────────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │          【 EXPORT 】          │
                    ├───────────────────────────────┤
                    │  ⑫ HTML ✅    ⑬ PDF ✅       │
                    │  ⑭ HWPX/HWP ✅  ⑮ PPT ❌     │
                    └───────────────────────────────┘
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │          【 SERVER 】          │
                    │     ⑯ 서버 업로드/공유 ❌      │
                    └───────────────────────────────┘
```

### 기능별 구현 현황

| # | 구분 | 기능 | 상태 | 구현 위치 |
|---|------|------|------|-----------|
| 1 | INPUT | 로컬 문서 RAG화 | ✅ 완료 | converters/pipeline/* |
| 2 | INPUT | 웹 문서 수집 | ❌ 미구현 | - |
| 3 | INPUT | HTML 표준화 | ❓ 미확인 | - |
| 4 | INPUT | 반영 수준 선택 | ⏳ UI만 존재 | index.html (추후 개발) |
| 5 | OUTPUT | 기획서 생성 | ✅ 완료 | handlers/briefing/ |
| 6 | OUTPUT | 보고서 생성 | ✅ 완료 | handlers/report/ |
| 7 | OUTPUT | 발표자료 생성 | ⏳ 준비중 | config.json (enabled:false) |
| 8 | OUTPUT | 신규 문서유형 | ✅ 완료 | handlers/doc_type_analyzer |
| 9 | EDIT | 웹 편집기 | ✅ 완료 | static/js/editor.js |
| 10 | EDIT | AI 편집 | ✅ 완료 | /refine, /refine-selection |
| 11 | EDIT | 신규 템플릿 | ✅ 완료 | handlers/template_manager |
| 12 | EXPORT | HTML | ✅ 완료 | app.py /download/html |
| 13 | EXPORT | PDF | ✅ 완료 | app.py /download/pdf |
| 14 | EXPORT | HWPX/HWP | ✅ 완료 | converters/html_to_hwp* |
| 15 | EXPORT | PPT | ❌ 미구현 | - |
| 16 | SERVER | 서버 업로드 | ❌ 미구현 | - |

---

## 3. 폴더 구조 (전체)

```
글벗/
│
├── app.py                              ✅ Flask 메인 (25개 API 엔드포인트)
│
├── handlers/                           ✅ 【PROCESS】 핵심 처리 모듈
│   ├── __init__.py
│   ├── common.py                       ✅ AI 호출 공통 (call_claude 등)
│   │
│   │── 【프로세서 4종】
│   ├── briefing/                       ✅ 기획서 처리
│   │   ├── processor.py                   BriefingProcessor
│   │   └── prompts/
│   │       ├── step1_extract.txt          구조 추출
│   │       ├── step1_5_plan.txt           배치 계획
│   │       └── step2_generate.txt         HTML 생성
│   │
│   ├── report/                         ✅ 보고서 처리
│   │   ├── processor.py                   ReportProcessor
│   │   └── prompts/
│   │       └── refine_selection.txt       부분 수정
│   │
│   ├── template/                       ✅ 템플릿 처리 (v3)
│   │   ├── processor.py                   TemplateProcessor
│   │   ├── html_table_template_css.txt
│   │   └── prompts/
│   │       └── analyze_template.txt
│   │
│   ├── custom_doc_type.py              ✅ 사용자 정의 문서 (user_*)
│   │
│   │── 【HWPX 분석 파이프라인】
│   ├── doc_type_analyzer.py            ✅ 6단계 SSE 오케스트레이터
│   ├── doc_template_analyzer.py        ✅ tools/ 호출 → template_info
│   ├── template_manager.py             ✅ template.html 생성/저장/로드
│   ├── style_generator.py              ✅ template_info → CSS
│   ├── semantic_mapper.py              ✅ 표 역할 분류
│   ├── content_analyzer.py             ✅ content_prompt.json 생성
│   │
│   └── tools/                          ✅ HWPX 파싱 도구 (12개)
│       ├── page_setup.py                  §7 용지/여백
│       ├── char_style.py                  §4 글자 모양 → cpr-*
│       ├── para_style.py                  §5 문단 모양 → ppr-*
│       ├── border_fill.py                 §2 테두리/배경 → bf-*
│       ├── table.py                       §6 표
│       ├── header_footer.py               §8 머리말/꼬리말
│       ├── content_order.py               본문 순서
│       ├── font.py                        §3 글꼴
│       ├── style_def.py                   스타일 정의
│       ├── numbering.py                   번호매기기
│       ├── image.py                       이미지
│       └── section.py                     §9 구역
│
├── converters/                         ✅ 【EXPORT】 변환 모듈
│   ├── __init__.py
│   │
│   │── 【HTML → HWP 변환】
│   ├── html_to_hwp.py                  ✅ 일반 문서 → HWP
│   ├── html_to_hwp_briefing.py         ✅ 기획서 → HWP
│   ├── hwp_style_mapping.py            ✅ 스타일 매핑 정의
│   ├── hwpx_style_injector.py          ✅ HWPX 스타일 주입
│   ├── hwpx_table_injector.py          ✅ HWPX 표 주입
│   ├── style_analyzer.py               ✅ HTML 스타일 분석
│   │
│   │── 【미사용】
│   ├── hwpx_generator.py               ❌ 미사용 (독립 실행용/개발중)
│   │
│   └── pipeline/                       ✅ 【INPUT】 RAG 파이프라인
│       ├── router.py                      분기 처리
│       ├── step1_convert.py               파일 변환 (hwp,pdf,ppt→pdf)
│       ├── step2_extract.py               텍스트/이미지 추출
│       ├── step3_domain.py                도메인 분석
│       ├── step4_chunk.py                 청킹
│       ├── step5_rag.py                   RAG 검색
│       ├── step6_corpus.py                코퍼스 구축
│       ├── step7_index.py                 인덱싱
│       ├── step8_content.py               콘텐츠 생성
│       └── step9_html.py                  HTML 생성
│
├── domain/                             ✅ 도메인 유틸리티
│   └── hwpx/
│       ├── hwpx_domain_guide.md           HWPX ↔ HTML 매핑 스펙 (§1~§11)
│       └── hwpx_utils.py                  단위 변환 함수
│
├── static/                             ✅ 【EDIT】 웹 편집기
│   ├── js/
│   │   └── editor.js                   ✅ 편집기 (1208줄)
│   │       · 폰트/크기/색상/정렬
│   │       · 굵게/기울임/밑줄/취소선
│   │       · 표/그림/구분선 삽입
│   │       · 지능형 정렬 (smartAlign)
│   │       · 새 페이지 / 전 페이지 이동
│   │       · Undo/Redo
│   │
│   └── css/
│       └── editor.css                  ✅ 편집기 스타일 (296줄)
│
├── templates/                          ✅ UI + 데이터 저장소
│   ├── index.html                      ✅ 메인 UI (3765줄)
│   │
│   │── 【미사용 - 삭제 가능】
│   ├── hwp_guide.md                    ❌ 미사용
│   ├── hwp_html_defaults.json          ❌ 미사용
│   │
│   ├── default/doc_types/              ✅ 기본 문서 유형 (3개)
│   │   ├── briefing/config.json           기획서 ✅
│   │   ├── report/config.json             보고서 ✅
│   │   └── presentation/config.json       발표자료 ⏳ (enabled:false)
│   │
│   └── user/                           ✅ 사용자 정의 저장
│       ├── doc_types/{type_id}/
│       │   ├── config.json
│       │   └── content_prompt.json
│       └── templates/{tpl_id}/
│           ├── template.html
│           ├── style.json
│           ├── meta.json
│           └── semantic_map.json
│
├── output/                             ⚠️ 임시 출력 (.gitignore 권장)
│   └── assets/*.png
│
└── prompts/                            ❌ 미사용 (중복 - 삭제 가능)
    ├── step1_extract.txt                  = briefing/prompts/ 와 동일
    ├── step1_5_plan.txt
    └── step2_generate.txt
```

---

## 4. API 엔드포인트 (25개)

### 메인
| API | 메서드 | 설명 |
|-----|--------|------|
| `/` | GET | 메인 페이지 (index.html) |
| `/health` | GET | 헬스 체크 |

### 문서 유형 관리
| API | 메서드 | 설명 |
|-----|--------|------|
| `/api/doc-types` | GET | 문서 유형 목록 |
| `/api/doc-types` | POST | 문서 유형 저장 |
| `/api/doc-types/<id>` | DELETE | 문서 유형 삭제 |
| `/api/doc-types/analyze` | POST | 문서 유형 분석 (단일) |
| `/api/doc-types/analyze-stream` | POST | 문서 유형 분석 (SSE 스트리밍) |
| `/api/doc-types/<id>/template` | GET | 템플릿 조회 |
| `/api/doc-types/<id>/template` | PUT | 템플릿 연결 |

### 템플릿 관리
| API | 메서드 | 설명 |
|-----|--------|------|
| `/templates` | GET | 템플릿 목록 |
| `/api/templates` | GET | 템플릿 목록 (API) |
| `/api/templates/<id>` | GET | 템플릿 상세 |
| `/api/templates/<id>` | DELETE | 템플릿 삭제 |
| `/analyze-template` | POST | HWPX → 템플릿 추출 |
| `/delete-template/<id>` | DELETE | 템플릿 삭제 (구버전) |

### 문서 생성
| API | 메서드 | 설명 |
|-----|--------|------|
| `/generate` | POST | 문서 생성 (briefing/report/template/custom) |
| `/generate-report` | POST | 보고서 생성 |

### 편집 (EDIT)
| API | 메서드 | 설명 |
|-----|--------|------|
| `/refine` | POST | AI 전체 수정 |
| `/refine-selection` | POST | AI 부분 수정 |
| `/analyze-styles` | POST | HTML 스타일 분석 |

### 다운로드 (EXPORT)
| API | 메서드 | 설명 |
|-----|--------|------|
| `/download/html` | POST | HTML 다운로드 |
| `/download/pdf` | POST | PDF 다운로드 (weasyprint) |
| `/export-hwp` | POST | HWP/HWPX 다운로드 |

### 기타
| API | 메서드 | 설명 |
|-----|--------|------|
| `/assets/<filename>` | GET | 로컬 에셋 서빙 |
| `/hwp-script` | GET | HWP 변환 안내 |

---

## 5. 모듈 연결도

```
                                 app.py (Flask)
                                      │
         ┌──────────┬─────────────────┼─────────────────┬──────────┐
         │          │                 │                 │          │
         ▼          ▼                 ▼                 ▼          ▼
    ┌────────┐ ┌────────┐       ┌──────────┐     ┌────────┐ ┌────────┐
    │briefing│ │ report │       │ template │     │ custom │ │doc_type│
    │Processor│ │Processor│      │Processor │     │DocType │ │Analyzer│
    └───┬────┘ └───┬────┘       └────┬─────┘     └───┬────┘ └───┬────┘
        │          │                 │               │          │
        │          ▼                 │               │          │
        │    ┌──────────┐            │               │          │
        │    │converters│            │               │          │
        │    │/pipeline │            │               │          │
        │    │ (RAG 9단계)│           │               │          │
        │    └──────────┘            │               │          │
        │                            │               │          │
        │                            ▼               ▼          ▼
        │                     ┌─────────────────────────────────────┐
        │                     │         template_manager             │
        │                     │  ┌─────────────────────────────────┐│
        │                     │  │ doc_template_analyzer            ││
        │                     │  │      └─ tools/* (12개)           ││
        │                     │  │            └─ domain/hwpx        ││
        │                     │  ├─────────────────────────────────┤│
        │                     │  │ style_generator                  ││
        │                     │  │ semantic_mapper                  ││
        │                     │  │ content_analyzer                 ││
        │                     │  └─────────────────────────────────┘│
        │                     └─────────────────────────────────────┘
        │
        │    ┌─────────────────────────────────────────────────────┐
        └───▶│              converters/ (EXPORT)                   │
             ├─────────────────────────────────────────────────────┤
             │  html_to_hwp_briefing  ◀── doc_type == 'briefing'   │
             │  html_to_hwp           ◀── 그 외                    │
             │       │                                             │
             │       ├── hwp_style_mapping                         │
             │       ├── hwpx_style_injector                       │
             │       ├── hwpx_table_injector                       │
             │       └── style_analyzer                            │
             └─────────────────────────────────────────────────────┘

                     ┌─────────────────────────────────────────────┐
                     │           static/ (EDIT 모듈)               │
                     ├─────────────────────────────────────────────┤
                     │  js/editor.js (1208줄)                      │
                     │    · 포맷 바 (폰트, 크기, 색상, 정렬)         │
                     │    · 삽입 (표, 그림, 구분선)                  │
                     │    · 페이지 관리 (새페이지, 이동)             │
                     │    · Undo/Redo                              │
                     │                                             │
                     │  css/editor.css (296줄)                     │
                     │    · 포맷 바 스타일                          │
                     │    · 편집 모드 하이라이트                     │
                     └─────────────────────────────────────────────┘
```

---

## 6. 핵심 파이프라인

### Phase A: 문서 유형 등록 (1회)
```
HWPX 업로드 + 이름 입력
      │
      ▼
doc_type_analyzer.analyze() [SSE 6단계]
      │
      ├─ Step 1: _parse_hwpx()           HWPX ZIP 해제
      ├─ Step 2: _extract_layout()       레이아웃 추출
      ├─ Step 3: _analyze_context()      [AI] 맥락 분석
      ├─ Step 4: _analyze_structure()    [AI] 구조 분석
      ├─ Step 5: template_manager.extract_and_save()
      │            ├─ doc_template_analyzer.analyze()
      │            │     └─ tools/* (12개 파싱 도구)
      │            ├─ semantic_mapper.generate()
      │            ├─ style_generator.generate_css()
      │            └─ content_analyzer.generate()
      └─ Step 6: save_doc_type()         저장

저장 위치:
  templates/user/doc_types/{type_id}/
    ├─ config.json
    └─ content_prompt.json
  templates/user/templates/{tpl_id}/
    ├─ template.html
    ├─ style.json
    ├─ meta.json
    └─ semantic_map.json
```

### Phase B: 문서 생성 (매번)
```
내용 입력 + 문서유형 선택
      │
      ├─ doc_type == 'briefing'
      │     └─ BriefingProcessor.generate()
      │          Step 1: 구조 추출 [AI]
      │          Step 1.5: 배치 계획 [AI]
      │          Step 2: HTML 생성 [AI]
      │
      ├─ doc_type == 'report'
      │     └─ ReportProcessor.generate()
      │          └─ converters/pipeline/router
      │               └─ 9단계 RAG 파이프라인
      │
      ├─ doc_type == 'template'
      │     └─ TemplateProcessor.generate()
      │
      └─ doc_type.startswith('user_')
            └─ CustomDocTypeProcessor.generate()
                 ├─ config.json 로드
                 ├─ template.html 로드
                 ├─ content_prompt.json 로드
                 ├─ [AI] placeholder 채우기
                 └─ _fill_template()
```

### Phase C: EXPORT
```
HTML 결과물
      │
      ├─ /download/html → 그대로 다운로드
      │
      ├─ /download/pdf → weasyprint 변환
      │
      └─ /export-hwp
           ├─ doc_type == 'briefing'
           │     └─ html_to_hwp_briefing.py
           └─ 그 외
                 └─ html_to_hwp.py
                      ├─ hwp_style_mapping
                      ├─ hwpx_style_injector
                      └─ hwpx_table_injector
```

---

## 7. 파일별 사용 현황

### 사용 중 (유지)
| 위치 | 파일 수 | 비고 |
|------|---------|------|
| handlers/ | 20개 | 전부 사용 |
| handlers/tools/ | 12개 | 전부 사용 |
| converters/ | 9개 | hwpx_generator.py 제외 |
| converters/pipeline/ | 10개 | 전부 사용 |
| domain/hwpx/ | 2개 | 전부 사용 |
| static/ | 2개 | 전부 사용 (EDIT 모듈) |
| templates/index.html | 1개 | 메인 UI |
| templates/default/ | 3개 | 기본 문서유형 |
| templates/user/ | 가변 | 사용자 데이터 |

### 미사용 (삭제 가능)
| 파일 | 이유 |
|------|------|
| `converters/hwpx_generator.py` | 어디서도 import 안 됨 |
| `templates/hwp_guide.md` | 어디서도 참조 안 됨 |
| `templates/hwp_html_defaults.json` | 어디서도 참조 안 됨 |
| `prompts/` (루트 폴더) | handlers/briefing/prompts/와 중복 |

### .gitignore 권장
```
output/
*/__pycache__/
*.pyc
```

---

## 8. 현재 버그 (3건)

### 🔴 버그 #1: 표 누락
- **위치**: template_manager.py
- **원인**: content_order의 table_idx가 header/footer 표 포함된 전체 리스트에 매핑
- **증상**: 본문 표가 사라짐

### 🔴 버그 #2: CSS 탈락  
- **위치**: custom_doc_type.py _fill_template()
- **원인**: `<p><span>` 안에 `<ul>` 삽입 → 브라우저가 구조 깨뜨림
- **증상**: 개조식 내용에 스타일 미적용

### 🔴 버그 #3: 제목 빈칸
- **위치**: content_analyzer.py
- **원인**: placeholder 이름 불일치 (TITLE vs TITLE_R1_C2)
- **증상**: 제목이 채워지지 않음

---

## 9. 다음 단계

### 즉시 수정 (버그 3건)
1. template_manager.py — 표 인덱스 매핑
2. custom_doc_type.py — inline context에서 `<ul>` 금지
3. content_analyzer.py — TITLE placeholder 이름

### 미구현 기능
- ② 웹 문서 수집 (크롤링)
- ④ 반영 수준 선택 (UI만 존재, 백엔드 미연결)
- ⑦ 발표자료 생성
- ⑮ PPT 출력
- ⑯ 서버 업로드/공유

---

*이 문서를 읽은 AI/개발자는 버그 수정 또는 미구현 기능 개발부터 시작할 수 있습니다.*